<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node453.html" />
<link rel="prev" href="ctypes-accessing-functions-from-loaded-dlls.html" />
<link rel="parent" href="ctypes-ctypes-tutorial.html" />
<link rel="next" href="node453.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>14.14.1.3 Calling functions</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="14.14.1.2 accessing functions from"
  href="ctypes-accessing-functions-from-loaded-dlls.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="14.14.1 ctypes tutorial"
  href="ctypes-ctypes-tutorial.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="14.14.1.4 fundamental data types"
  href="node453.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="ctypes-accessing-functions-from-loaded-dlls.html">14.14.1.2 Accessing functions from</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ctypes-ctypes-tutorial.html">14.14.1 ctypes tutorial</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node453.html">14.14.1.4 Fundamental data types</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h3><a name="SECTION00161413000000000000000"></a><a name="ctypes-calling-functions"></a>
<br>
14.14.1.3 Calling functions
</h3>

<p>
You can call these functions like any other Python callable. This
example uses the <code>time()</code> function, which returns system time in
seconds since the <span class="Unix">Unix</span> epoch, and the <code>GetModuleHandleA()</code> function,
which returns a win32 module handle.

<p>
This example calls both functions with a NULL pointer (<code>None</code> should
be used as the NULL pointer):
<div class="verbatim"><pre>
&gt;&gt;&gt; print libc.time(None) # doctest: +SKIP
1150640792
&gt;&gt;&gt; print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS
0x1d000000
&gt;&gt;&gt;
</pre></div>

<p>
<code>ctypes</code> tries to protect you from calling functions with the wrong
number of arguments or the wrong calling convention.  Unfortunately
this only works on Windows.  It does this by examining the stack after
the function returns, so although an error is raised the function
<em>has</em> been called:
<div class="verbatim"><pre>
&gt;&gt;&gt; windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS
Traceback (most recent call last):
  File "&lt;stdin&gt;", line 1, in ?
ValueError: Procedure probably called with not enough arguments (4 bytes missing)
&gt;&gt;&gt; windll.kernel32.GetModuleHandleA(0, 0) # doctest: +WINDOWS
Traceback (most recent call last):
  File "&lt;stdin&gt;", line 1, in ?
ValueError: Procedure probably called with too many arguments (4 bytes in excess)
&gt;&gt;&gt;
</pre></div>

<p>
The same exception is raised when you call an <code>stdcall</code> function
with the <code>cdecl</code> calling convention, or vice versa:
<div class="verbatim"><pre>
&gt;&gt;&gt; cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS
Traceback (most recent call last):
  File "&lt;stdin&gt;", line 1, in ?
ValueError: Procedure probably called with not enough arguments (4 bytes missing)
&gt;&gt;&gt;

&gt;&gt;&gt; windll.msvcrt.printf("spam") # doctest: +WINDOWS
Traceback (most recent call last):
  File "&lt;stdin&gt;", line 1, in ?
ValueError: Procedure probably called with too many arguments (4 bytes in excess)
&gt;&gt;&gt;
</pre></div>

<p>
To find out the correct calling convention you have to look into the C
header file or the documentation for the function you want to call.

<p>
On Windows, <code>ctypes</code> uses win32 structured exception handling to
prevent crashes from general protection faults when functions are
called with invalid argument values:
<div class="verbatim"><pre>
&gt;&gt;&gt; windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS
Traceback (most recent call last):
  File "&lt;stdin&gt;", line 1, in ?
WindowsError: exception: access violation reading 0x00000020
&gt;&gt;&gt;
</pre></div>

<p>
There are, however, enough ways to crash Python with <code>ctypes</code>, so
you should be careful anyway.

<p>
<code>None</code>, integers, longs, byte strings and unicode strings are the
only native Python objects that can directly be used as parameters in
these function calls.  <code>None</code> is passed as a C <code>NULL</code> pointer,
byte strings and unicode strings are passed as pointer to the memory
block that contains their data (<code>char *</code> or <code>wchar_t *</code>).  Python
integers and Python longs are passed as the platforms default C
<code>int</code> type, their value is masked to fit into the C type.

<p>
Before we move on calling functions with other parameter types, we
have to learn more about <code>ctypes</code> data types.

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="14.14.1.2 accessing functions from"
  href="ctypes-accessing-functions-from-loaded-dlls.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="14.14.1 ctypes tutorial"
  href="ctypes-ctypes-tutorial.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="14.14.1.4 fundamental data types"
  href="node453.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="ctypes-accessing-functions-from-loaded-dlls.html">14.14.1.2 Accessing functions from</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ctypes-ctypes-tutorial.html">14.14.1 ctypes tutorial</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node453.html">14.14.1.4 Fundamental data types</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
